﻿/*
Copyright © 2011 François Karman

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

See <license.txt> for the complete license of the software.
*/

using System;
using System.Collections.Generic;

namespace Simple.Storage
{
    /// <summary>
    /// Defines the concept of persisted class.
    /// </summary>
    /// <remarks>
    /// The implementations of this interface should be immutable to avoid any side effect.
    /// </remarks>
    public interface IClassDefinition
    {
        /// <summary>
        /// Gets the type of the persisted instances.
        /// </summary>
        Type Type { get; }

        /// <summary>
        /// Gets the type of the associated key.
        /// </summary>
        Type KeyType { get; }

        /// <summary>
        /// Gets the definitions of the serialized properties.
        /// </summary>
        ICollection<IPropertyDefinition> Properties { get; }

        /// <summary>
        /// Retrieves the unique key of an object associated with this definition.
        /// </summary>
        /// <param name="value">A <see cref="IClassDefinition.Type"/> instance.</param>
        /// <returns>
        /// The associated identifier  of <see cref="IClassDefinition.KeyType"/> type.
        /// </returns>
        object RetrieveKey(object value);

        /// <summary>
        /// Creates an new instance of the persisted class.
        /// </summary>
        /// <param name="key">
        /// The unique key of the instance of <see cref="IClassDefinition.KeyType"/> type.
        /// </param>
        /// <returns>
        /// The created <see cref="IClassDefinition.Type"/> instance.
        /// </returns>
        /// <remarks>
        /// The <paramref name="key"/> should only be used if the key
        /// is not part of the serialized properties.
        /// </remarks>
        /// <exception cref="ArgumentNullException">
        /// The <paramref name="key"/> parameter is <c>null</c>.
        /// </exception>
        /// <exception cref="WrongKeyTypeException">
        /// The <paramref name="key"/> is not a <see cref="IClassDefinition.KeyType"/> instance.
        /// </exception>
        object CreateInstance(object key);
    }
}
